home *** CD-ROM | disk | FTP | other *** search
/ Aminet 1 (Walnut Creek) / Aminet - June 1993 [Walnut Creek].iso / usenet / sources / volume2 / libraris / gimme.1 next >
Internet Message Format  |  1988-12-02  |  58KB
  1. Path: xanth!ames!nrl-cmf!ukma!rutgers!mit-eddie!ll-xn!adelie!infinet!ulowell!page
  2. From: page@swan.ulowell.edu (Bob Page)
  3. Newsgroups: comp.sources.amiga
  4. Subject: v02i074:  gimme.lib - misc library routines, Part01/07
  5. Message-ID: <10412@swan.ulowell.edu>
  6. Date: 2 Dec 88 00:58:14 GMT
  7. Organization: University of Lowell, Computer Science Dept.
  8. Lines: 1678
  9. Approved: page@swan.ulowell.edu
  10.  
  11. Submitted-by: oscvax!jan@uunet.UU.NET (Jan Sven Trabandt)
  12. Posting-number: Volume 2, Issue 74
  13. Archive-name: libraries/gimme.1
  14.  
  15. Gimme.lib is a bunch of routines I've grouped together over the year
  16. and is particularly useful for dealing with Intuition structures as
  17. well as some devices.  It's a (Manx) library to be linked in to a
  18. program.
  19.  
  20. Look at the file "gimmefuncs.h" to see the function prototypes
  21. for the whole kit-and-kaboodle (there are around 120 functions).
  22.  
  23. #    This is a shell archive.
  24. #    Remove everything above and including the cut line.
  25. #    Then run the rest of the file through sh.
  26. #----cut here-----cut here-----cut here-----cut here----#
  27. #!/bin/sh
  28. # shar:    Shell Archiver
  29. #    Run the following text with /bin/sh to create:
  30. #    DOCS.part1
  31. # This archive created: Thu Dec  1 19:44:20 1988
  32. cat << \SHAR_EOF > DOCS.part1
  33. /*
  34.  * NAME:    gimmeBitMap
  35.  *
  36.  * SYNOPSIS:    bm = gimmeBitMap( depth, width, height );
  37.  *        struct BitMap *bm;
  38.  *
  39.  * INPUTS:    SHORT    depth;        number of required bitplanes
  40.  *        SHORT    width;        number of columns wide in pixels
  41.  *        SHORT    height;     number of rows high in pixels
  42.  *
  43.  * DESCRIPTION: Allocate and initialize/clear a BitMap struct.
  44.  *        If the depth, width and height parameters are strictly positive,
  45.  *        the required bit-planesare allocated as well, and the BitMap
  46.  *        is properly initialized,
  47.  *        otherwise the BitMap is cleared.
  48.  *
  49.  * RESULTS:    Returns pointer to a BitMap, or NULL if anything went wrong.
  50.  *
  51.  * SEE ALSO:    getRidOfBitMap
  52.  */
  53.  
  54. /*
  55.  * NAME:    getRidOfBitMap
  56.  *
  57.  * SYNOPSIS:    err = getRidOfBitMap( bitmap );
  58.  *        short err;
  59.  *
  60.  * INPUTS:    struct BitMap    *bitmap;    pointer to initialized bitmap
  61.  *
  62.  * DESCRIPTION: Deallocate memory for a bitmap, including bitplanes.
  63.  *        Number of bitplanes determined from bitmap.
  64.  *
  65.  * RESULTS:    Returns non-zero on error.
  66.  *
  67.  * SEE ALSO:    gimmeBitMap
  68.  */
  69.  
  70. /*
  71.  * NAME:    gimmeBitPlanes
  72.  *
  73.  * SYNOPSIS:    flags = gimmeBitPlanes( bm, myflags );
  74.  *        ULONG flags;
  75.  *
  76.  * INPUTS:    struct BitMap    *bm;        ptr to initialized BitMap
  77.  *        ULONG        myflags;    flags for routine
  78.  *
  79.  * DESCRIPTION: Allocate bit-plane(s) given an initialized BitMap struct,
  80.  *        according to the flags:
  81.  *          - contiguous    - all planes allocated contiguously,
  82.  *                    as required for Image data
  83.  *          - separate    - all planes allocated individually
  84.  *          - default    - try contiguous first, then separate
  85.  *
  86.  *        Note: the "initialized" BitMap struct should not have any
  87.  *        planes allocated for it prior to this call, as the plane
  88.  *        pointers are stored in the BitMap's Planes[] field.
  89.  *
  90.  * RESULTS:    Returns actual flags used.
  91.  *        Check if bm->Planes[0] is non-NULL to see if successfull,
  92.  *        or if the returned flags equals the error flag defined in
  93.  *        bitplane.h
  94.  *
  95.  * SEE ALSO:    getRidOfBitPlanes
  96.  */
  97.  
  98. /*
  99.  * NAME:    getRidOfBitPlanes
  100.  *
  101.  * SYNOPSIS:    err = getRidOfBitPlanes( bitmap, myflags );
  102.  *        short err;
  103.  *
  104.  * INPUTS:    struct BitMap    *bitmap;    pointer to initialized bitmap
  105.  *        ULONG        myflags;    flags for routine
  106.  *
  107.  * DESCRIPTION: Deallocate memory for a bitmap's bitplanes.
  108.  *        Number of bitplanes determined from bitmap.
  109.  *
  110.  * RESULTS:    Returns non-zero on error.
  111.  *
  112.  * SEE ALSO:    gimmeBitPlanes
  113.  */
  114.  
  115. /*
  116.  * NAME:    getDefaultColors
  117.  *
  118.  * SYNOPSIS:    colortable = getDefaultColors();
  119.  *        USHORT *colortable;
  120.  *
  121.  * DESCRIPTION: Get pointer to the default color table.
  122.  *
  123.  * RESULTS:    Returns pointer to the default color table,
  124.  *        or NULL if there is none.
  125.  */
  126.  
  127. /*
  128.  * NAME:    setColors
  129.  *
  130.  * SYNOPSIS:    error = setColors( screen, colortable, colors );
  131.  *        short error;
  132.  *
  133.  * INPUTS:    struct Screen    *screen;    pointer to Intuition screen
  134.  *        USHORT    *colortable;        or use NULL for default color table
  135.  *        SHORT    colors;         number of colors to set
  136.  *
  137.  * DESCRIPTION: Set the colors of an Intuition screen.
  138.  *
  139.  * RESULTS:    Returns non-zero on error (eg. if default color table
  140.  *        requested but not large enough).
  141.  */
  142.  
  143. /*
  144.  * NAME:    checkColors
  145.  *
  146.  * SYNOPSIS:    err = checkColors( screen, colors );
  147.  *        short err;
  148.  *
  149.  * INPUTS:    struct Screen    *screen;    pointer to Intuition screen
  150.  *        SHORT    colors;         number of colors to check
  151.  *
  152.  * DESCRIPTION: Check colors of an Intuition screen by writing "hi!" in
  153.  *        every color on the screen.
  154.  *
  155.  *        Note: This is intended for "debug" purposes, as it will
  156.  *        overwrite the screen's display.
  157.  *
  158.  * RESULTS:    Returns non-zero on error.
  159.  */
  160.  
  161. /*
  162.  * NAME:    c_init
  163.  *
  164.  * SYNOPSIS:    err = c_init();
  165.  *        short err;
  166.  *
  167.  * DESCRIPTION: Initialize the communication interface software.
  168.  *
  169.  * RESULTS:    Returns a non-zero code on error (see gimmelib/shandler.h).
  170.  *
  171.  * SEE ALSO:    c_open
  172.  */
  173.  
  174. /*
  175.  * NAME:    c_open
  176.  *
  177.  * SYNOPSIS:    err = c_open( parms );
  178.  *        short err;
  179.  *
  180.  * INPUTS:    struct c_parameters *parms;    serial setup parameters
  181.  *
  182.  * DESCRIPTION: Open the communications channel to the serial device.
  183.  *
  184.  * RESULTS:    Returns a non-zero code on error (see gimmelib/shandler.h).
  185.  *
  186.  * SEE ALSO:    c_setup, c_init
  187.  */
  188.  
  189. /*
  190.  * NAME:    c_setup
  191.  *
  192.  * SYNOPSIS:    err = c_setup( parms );
  193.  *        short err;
  194.  *
  195.  * INPUTS:    struct c_parameters *parms;    serial setup parameters
  196.  *
  197.  * DESCRIPTION: Set the parameters that configure the serial port for
  198.  *        communication.
  199.  *        The different modes for serial configuration are not set in
  200.  *        this function. They are only done in c_open.
  201.  *
  202.  *        NOTE: the serial port must already be successfully opened by
  203.  *        c_open and there should be no pending commands on the port.
  204.  *
  205.  * RESULTS:    Returns a non-zero error code (see shandler.h) upon error.
  206.  *
  207.  * SEE ALSO:    c_open
  208.  */
  209.  
  210. /*
  211.  * NAME:    c_getc
  212.  *
  213.  * SYNOPSIS:    err = c_getc( charptr );
  214.  *        short err;
  215.  *
  216.  * INPUTS:    char    *charptr;    pointer to location to put character
  217.  *
  218.  * DESCRIPTION: Get a single character from the serial channel, with a
  219.  *        "large" timeout.
  220.  *
  221.  * RESULTS:    Returns a non-zero code on error (see gimmelib/shandler.h).
  222.  *
  223.  * SEE ALSO:    c_gets, c_getline, c_emptyc
  224.  */
  225.  
  226. /*
  227.  * NAME:    c_emptyc
  228.  *
  229.  * SYNOPSIS:    err = c_emptyc();
  230.  *        short err;
  231.  *
  232.  * DESCRIPTION: Flush the buffer, with a "small" timeout.
  233.  *
  234.  * RESULTS:    Returns a non-zero code on error (see gimmelib/shandler.h).
  235.  *
  236.  * SEE ALSO:    c_getc, c_gets, c_getline
  237.  */
  238.  
  239. /*
  240.  * NAME:    c_putc
  241.  *
  242.  * SYNOPSIS:    err = c_putc( character );
  243.  *        short err;
  244.  *
  245.  * INPUTS:    char    character;        character to send
  246.  *
  247.  * DESCRIPTION: Send one character to the serial channel.
  248.  *
  249.  * RESULTS:    Returns a non-zero code on error (see gimmelib/shandler.h).
  250.  *
  251.  * SEE ALSO:    c_puts
  252.  */
  253.  
  254. /*
  255.  * NAME:    c_gets
  256.  *
  257.  * SYNOPSIS:    err = c_gets( buffer, num_to_get );
  258.  *        short err;
  259.  *
  260.  * INPUTS:    char    *buffer;    buffer to store characters
  261.  *        SHORT    num_to_get;    number of characters to get
  262.  *
  263.  * DESCRIPTION: Get the specified number of characters from
  264.  *        the input channel and places them in the buffer.
  265.  *        Note: does NOT stop reading on a '\0', nor is a '\0' appended.
  266.  *
  267.  * RESULTS:    Returns a non-zero code on error (see gimmelib/shandler.h).
  268.  *
  269.  * SEE ALSO:    c_getc, c_getline
  270.  */
  271.  
  272. /*
  273.  * NAME:    c_getline
  274.  *
  275.  * SYNOPSIS:    err = c_getline( buffer, num_to_get );
  276.  *        short err;
  277.  *
  278.  * INPUTS:    char    *buffer;    buffer to store characters
  279.  *        SHORT    num_to_get;    number of characters to get
  280.  *
  281.  * DESCRIPTION: Get up to the specified number of characters,
  282.  *        or until the end-of-line character is found,
  283.  *        from the input channel and place them in the buffer.
  284.  *        The default end-of-line character is 0x0d (CR) (check
  285.  *        gimmelib/shandler.h to be sure), but this can be changed
  286.  *        using the c_setEOL() routine.
  287.  *        Note: the end-of-line character is kept in the buffer
  288.  *        and NO '\0' is appended.
  289.  *
  290.  * RESULTS:    Returns a non-zero code on error (see gimmelib/shandler.h).
  291.  *
  292.  * SEE ALSO:    c_setEOL, c_getc, c_gets
  293.  */
  294.  
  295. /*
  296.  * NAME:    c_setEOL
  297.  *
  298.  * SYNOPSIS:    err = c_setEOL( eol_character )
  299.  *        short err;
  300.  *
  301.  * INPUTS:    char    eol_character;        new end-of-line character
  302.  *
  303.  * DESCRIPTION: Set the end-of-line character for use with c_getline().
  304.  *        Note: the end-of-line character must be changed (if desired)
  305.  *        after each c_open().
  306.  *
  307.  * RESULTS:    Returns a non-zero code on error (see gimmelib/shandler.h).
  308.  *
  309.  * SEE ALSO:    c_getline, c_open
  310.  */
  311.  
  312. /*
  313.  * NAME:    c_puts
  314.  *
  315.  * SYNOPSIS:    err = c_puts( buffer, num_to_put );
  316.  *        short err;
  317.  *
  318.  * INPUTS:    char    *buffer;
  319.  *        SHORT    num_to_put;
  320.  *
  321.  * DESCRIPTION: Send the specified number of characters to the serial port
  322.  *        starting at the location pointed to by buffer.
  323.  *
  324.  * RESULTS:    Returns a non-zero code on error (see gimmelib/shandler.h).
  325.  *
  326.  * SEE ALSO:    c_putc
  327.  */
  328.  
  329. /*
  330.  * NAME:    c_close
  331.  *
  332.  * SYNOPSIS:    err = c_close();
  333.  *        short err;
  334.  *
  335.  * DESCRIPTION: Close the communications channel.
  336.  *
  337.  * RESULTS:    Returns a non-zero code on error (see gimmelib/shandler.h).
  338.  *
  339.  * SEE ALSO:    c_init, c_open
  340.  */
  341.  
  342. /*
  343.  * NAME:    c_done
  344.  *
  345.  * SYNOPSIS:    err = c_done();
  346.  *        short err;
  347.  *
  348.  * DESCRIPTION: De-initialize the communication interface software,
  349.  *        i.e. tell it you are completely done with it.
  350.  *
  351.  * RESULTS:    Returns a non-zero code on error (see gimmelib/shandler.h).
  352.  *
  353.  * SEE ALSO:    c_init, c_open, c_close
  354.  */
  355.  
  356. /*
  357.  * NAME:    copyDataImage
  358.  *
  359.  * SYNOPSIS:    err = copyDataImage( data, image );
  360.  *        short err;
  361.  *
  362.  * INPUTS:    USHORT        *data;        pointer to start of data to copy
  363.  *        struct Image    *image;     image to receive data
  364.  *
  365.  * DESCRIPTION: Copy the data into the image's data buffer (in chip memory).
  366.  *        Note: the image must already have a data buffer.
  367.  *
  368.  * RESULTS:    Returns non-zero on error.
  369.  *
  370.  * SEE ALSO:    gimmeImage, copyImageData
  371.  */
  372.  
  373. /*
  374.  * NAME:    copyImageData
  375.  *
  376.  * SYNOPSIS:    err = copyImageData( image, data );
  377.  *        short err;
  378.  *
  379.  * INPUTS:    struct Image    *image;     image to receive data
  380.  *        USHORT        *data;        pointer to start of data to copy
  381.  *
  382.  * DESCRIPTION: Copy the image's actual data into a supplied buffer.
  383.  *
  384.  * RESULTS:    Returns non-zero on error.
  385.  *
  386.  * SEE ALSO:    gimmeImage, copyDataImage
  387.  */
  388.  
  389. /*
  390.  * NAME:    copyBorder
  391.  *
  392.  * SYNOPSIS:    border = copyBorder( memheadptr, oldborder, numbord, myflags );
  393.  *        struct Border *border;
  394.  *
  395.  * INPUTS:    void        **memheadptr;    pointer to chained-memory head
  396.  *        struct Border    *oldborder;    border to copy (first of list)
  397.  *        SHORT        numbord;    # of borders to copy, -1 for all
  398.  *        ULONG        myflags;    flags for this routine
  399.  *
  400.  * DESCRIPTION: Copy numbord Border structs beginning with oldborder.
  401.  *        A numbord of -1 means all the borders in the list.
  402.  *
  403.  *        The flags define how much detail should be copied.
  404.  *
  405.  *        NOTE: chainAllocMem is used and you
  406.  *        should use chainFreeMem eventually to free the memory;
  407.  *
  408.  * RESULTS:    Returns pointer to Border, or NULL.
  409.  *
  410.  * SEE ALSO:    chainAllocMem, chainFreeMem, gimmeBorder
  411.  */
  412.  
  413. /*
  414.  * NAME:    copyImage
  415.  *
  416.  * SYNOPSIS:    image = copyImage( memheadptr, oldimage, numimage, myflags );
  417.  *        struct Image *image;
  418.  *
  419.  * INPUTS:    void        **memheadptr;    pointer to chained-memory head
  420.  *        struct Image   *oldimage;     image to copy (first of list)
  421.  *        SHORT        numimage;     # of images to copy, -1 for all
  422.  *        ULONG        myflags;    flags for this routine
  423.  *
  424.  * DESCRIPTION: Copy numimage Image structs beginning with oldimage.
  425.  *        A numimage of -1 means all the images in the list.
  426.  *
  427.  *        The flags define how much detail should be copied.
  428.  *
  429.  *        NOTE: chainAllocMem is used and you
  430.  *        should use chainFreeMem eventually to free the memory;
  431.  *
  432.  * RESULTS:    Returns pointer to Image, or NULL.
  433.  *
  434.  * SEE ALSO:    chainAllocMem, chainFreeMem, gimmeImage
  435.  */
  436.  
  437. /*
  438.  * NAME:    copyIntuiText
  439.  *
  440.  * SYNOPSIS:    it = copyIntuiText( memheadptr, olditext, numitext, myflags );
  441.  *        struct IntuiText *it;
  442.  *
  443.  * INPUTS:    void         **memheadptr;     pointer to chained-memory head
  444.  *        struct IntuiText *olditext;     itext to copy (first of list)
  445.  *        SHORT         numitext;     # of itexts to copy, -1 for all
  446.  *        ULONG         myflags;     flags for this routine
  447.  *
  448.  * DESCRIPTION: Copy numitext IntuiText structs beginning with olditext.
  449.  *        A numitext of -1 means all the IntuiTexts in the list.
  450.  *
  451.  *        The flags define how much detail should be copied.
  452.  *
  453.  *        NOTE: chainAllocMem is used and you
  454.  *        should use chainFreeMem eventually to free the memory;
  455.  *
  456.  * RESULTS:    Returns pointer to IntuiText, or NULL.
  457.  *
  458.  * SEE ALSO:    chainAllocMem, chainFreeMem, gimmeIntuiText
  459.  */
  460.  
  461. /*
  462.  * NAME:    copyMenuItem
  463.  *
  464.  * SYNOPSIS:    item = copyMenuItem( memheadptr, olditem, numitem, numsub,
  465.  *                        myflags );
  466.  *        struct MenuItem *item;
  467.  *
  468.  * INPUTS:    void        **memheadptr;    pointer to chained-memory head
  469.  *        struct MenuItem *olditem;    item to copy (first of list)
  470.  *        SHORT        numitem;    #items to copy, -1 for all
  471.  *        SHORT        numsub;     #subitems to copy, -1 for all
  472.  *        ULONG        myflags;    flags for this routine
  473.  *
  474.  * DESCRIPTION: Copy numitem MenuItem structs beginning with olditem.
  475.  *        A numitem of -1 means all the items in the list.
  476.  *        For each MenuItem copied, numsub subitems will be copied as
  477.  *        well (a numsub of -1 means all subitems).
  478.  *
  479.  *        The flags define how much detail should be copied.
  480.  *
  481.  *        NOTE: chainAllocMem is used and you
  482.  *        should use chainFreeMem eventually to free the memory;
  483.  *
  484.  * RESULTS:    Returns pointer to MenuItem, or NULL.
  485.  *
  486.  * SEE ALSO:    chainAllocMem, chainFreeMem, gimmeMenuItem
  487.  */
  488.  
  489. /*
  490.  * NAME:    copyMenu
  491.  *
  492.  * SYNOPSIS:    menu = copyMenu( memheadptr, oldmenu, nummenu, numitem,
  493.  *                    numsub, myflags );
  494.  *        struct Menu *menu;
  495.  *
  496.  * INPUTS:    void        **memheadptr;    pointer to chained-memory head
  497.  *        struct Menu    *oldmenu;    menu to copy (first of list)
  498.  *        SHORT        nummenu;    #menus to copy, -1 for all
  499.  *        SHORT        numitem;    #menus to copy, -1 for all
  500.  *        SHORT        numsub;     #submenus to copy, -1 for all
  501.  *        ULONG        myflags;    flags for this routine
  502.  *
  503.  * DESCRIPTION: Copy nummenu Menu structs beginning with oldmenu.
  504.  *        A nummenu of -1 means all the menus in the list.
  505.  *        For each Menu copied, numitem menuitems will be copied as
  506.  *        well (a numitem of -1 means all menuitems) via copyMenuItem
  507.  *        using numsub for the number of subitems to copy.
  508.  *
  509.  *        The flags define how much detail should be copied.
  510.  *
  511.  *        NOTE: chainAllocMem is used and you
  512.  *        should use chainFreeMem eventually to free the memory;
  513.  *
  514.  * RESULTS:    Returns pointer to Menu, or NULL.
  515.  *
  516.  * SEE ALSO:    chainAllocMem, chainFreeMem, gimmeMenu, copyMenuItem
  517.  */
  518.  
  519. /*
  520.  * NAME:    makeDBuf
  521.  *
  522.  * SYNOPSIS:    err = makeDBuf( screen, bmptr );
  523.  *        short err;
  524.  *
  525.  * INPUTS:    struct Screen    *screen;    ptr to single-buffered screen
  526.  *        struct BitMap    **bmptr;    ptr to bitmap ptr for second buffer
  527.  *
  528.  * DESCRIPTION: Change a single-buffered Intuition screen into a
  529.  *        double-buffered screen.
  530.  *        If you already have your own bitmap for the secondary buffer,
  531.  *        bmptr should point to the bitmap pointer;
  532.  *        otherwise bmptr should point to a NULL pointer, in which case
  533.  *        a bitmap of the same depth/width/height as the screen is
  534.  *        dynamically created, and the pointer to this bitmap is
  535.  *        returned in *bmptr.
  536.  *
  537.  *        Note: you must not alter the bitmap pointer placed in *bmptr.
  538.  *
  539.  * RESULTS:    Returns non-zero on error.
  540.  *
  541.  * SEE ALSO:    unmakeDBuf, swapDBuf
  542.  */
  543.  
  544. /*
  545.  * NAME:    unmakeDBuf
  546.  *
  547.  * SYNOPSIS:    err = unmakeDBuf( screen, bmptr, bm );
  548.  *        short err;
  549.  *
  550.  * INPUTS:    struct Screen    *screen;    ptr to double-buffered screen
  551.  *        struct BitMap    **bmptr;    ptr to bitmap ptr for second buffer
  552.  *        struct BitMap    *bm;        ptr to bitmap to be freed
  553.  *
  554.  * DESCRIPTION: Changes a double-buffered screen [as made by makeDBuf]
  555.  *        back into a single-buffered screen.
  556.  *        The screen's buffers are swapped if necessary to ensure that
  557.  *        a CloseScreen() will work properly.
  558.  *        If bm is non-NULL, the bitmap will be freed (de-allocated);
  559.  *        this is intended primarily to be used to free the bitmap that
  560.  *        was created by makeDBuf if you did not previously have
  561.  *        a bitmap for the secondary buffer.
  562.  *
  563.  *        Note: the screen and bmptr parameters should be exactly the
  564.  *        same as those given to makeDBuf.
  565.  *
  566.  * RESULTS:    Returns non-zero on error.
  567.  *
  568.  * SEE ALSO:    makeDBuf, swapDBuf
  569.  */
  570.  
  571. /*
  572.  * NAME:    swapDBuf
  573.  *
  574.  * SYNOPSIS:    err = swapDBuf( screen, minterm );
  575.  *        short err;
  576.  *
  577.  * INPUTS:    struct Screen    *screen;    ptr to double-buffered screen
  578.  *        SHORT        minterm;    minterm for the copy
  579.  *
  580.  * DESCRIPTION: Switch the display and draw buffers for the screen.
  581.  *        The minterm is used to specify the type of blit used to copy
  582.  *        the new displayed buffer (source) to the new hidden/drawing
  583.  *        buffer (dest).
  584.  *        Some common minterms are:
  585.  *            0x000    - clear destination
  586.  *            0x0c0    - vanilla copy (result: source only)
  587.  *            0x0a0    - no copy (result: dest only)
  588.  *
  589.  *        Note: this routine hums along fine if the screen is not
  590.  *        actually double-buffered, doing no swap and no copy.
  591.  *
  592.  * RESULTS:    Returns non-zero on error.
  593.  *
  594.  * SEE ALSO:    makeDBuf, unmakeDBuf
  595.  */
  596.  
  597. /*
  598.  * NAME:    makeDBufQuick
  599.  *
  600.  * SYNOPSIS:    err = makeDBufQuick( screen, bmptr, lcprptr, scprptr );
  601.  *        short err;
  602.  *
  603.  * INPUTS:    struct Screen    *screen;    ptr to single-buffered screen
  604.  *        struct BitMap    **bmptr;    ptr to bitmap ptr for second buffer
  605.  *        struct cprlist    **lcprptr;  ptr to (long) copper list pointer
  606.  *        struct cprlist    **scprptr;  ptr to (short) copper list pointer
  607.  *
  608.  * DESCRIPTION: Change a single-buffered Intuition screen into a
  609.  *        double-buffered screen.
  610.  *        If you already have your own bitmap for the secondary buffer,
  611.  *        bmptr should point to the bitmap pointer;
  612.  *        otherwise bmptr should point to a NULL pointer, in which case
  613.  *        a bitmap of the same depth/width/height as the screen is
  614.  *        dynamically created, and the pointer to this bitmap is
  615.  *        returned in *bmptr.
  616.  *
  617.  *        Note: you must not alter the bitmap pointer placed in *bmptr.
  618.  *
  619.  * RESULTS:    Returns non-zero on error.
  620.  *
  621.  * SEE ALSO:    unmakeDBufQuick, swapDBufQuick
  622.  */
  623.  
  624. /*
  625.  * NAME:    unmakeDBufQuick
  626.  *
  627.  * SYNOPSIS:    err = unmakeDBufQuick( screen, bmptr, bm,
  628.  *                        lcprptr, scprptr );
  629.  *        short err;
  630.  *
  631.  * INPUTS:    struct Screen    *screen;    ptr to double-buffered screen
  632.  *        struct BitMap    **bmptr;    ptr to bitmap ptr for second buffer
  633.  *        struct BitMap    *bm;        ptr to bitmap to be freed
  634.  *        struct cprlist    **lcprptr;  ptr to (long) copper list pointer
  635.  *        struct cprlist    **scprptr;  ptr to (short) copper list pointer
  636.  *
  637.  * DESCRIPTION: Changes a double-buffered screen [as made by makeDBufQuick]
  638.  *        back into a single-buffered screen.
  639.  *        The screen's buffers are swapped if necessary to ensure that
  640.  *        a CloseScreen() will work properly.
  641.  *        If bm is non-NULL, the bitmap will be freed (de-allocated);
  642.  *        this is intended primarily to be used to free the bitmap that
  643.  *        was created by makeDBufQuick if you did not previously have
  644.  *        a bitmap for the secondary buffer.
  645.  *
  646.  *        Note: the screen and bmptr parameters should be exactly the
  647.  *        same as those given to makeDBufQuick.
  648.  *
  649.  * RESULTS:    Returns non-zero on error.
  650.  *
  651.  * SEE ALSO:    makeDBufQuick, swapDBufQuick
  652.  */
  653.  
  654. /*
  655.  * NAME:    swapDBufQuick
  656.  *
  657.  * SYNOPSIS:    err = swapDBufQuick( screen, minterm, lcprptr, scprptr );
  658.  *        short err;
  659.  *
  660.  * INPUTS:    struct Screen    *screen;    ptr to double-buffered screen
  661.  *        SHORT        minterm;    minterm for the copy
  662.  *        struct cprlist    **lcprptr;  ptr to (long) copper list pointer
  663.  *        struct cprlist    **scprptr;  ptr to (short) copper list pointer
  664.  *
  665.  * DESCRIPTION: Switch the display and draw buffers for the screen.
  666.  *        The minterm is used to specify the type of blit used to copy
  667.  *        the new displayed buffer (source) to the new hidden/drawing
  668.  *        buffer (dest).
  669.  *        Some common minterms are:
  670.  *            0x000    - clear destination
  671.  *            0x0c0    - vanilla copy (result: source only)
  672.  *            0x0a0    - no copy (result: dest only)
  673.  *
  674.  *        Note: this routine hums along fine if the screen is not
  675.  *        actually double-buffered, doing no swap and no copy.
  676.  *
  677.  * RESULTS:    Returns non-zero on error.
  678.  *
  679.  * SEE ALSO:    makeDBufQuick, unmakeDBufQuick
  680.  */
  681.  
  682. /*
  683.  * NAME:    makeDBufVQuick
  684.  *
  685.  * SYNOPSIS:    err = makeDBufVQuick( screen, bmptr );
  686.  *        short err;
  687.  *
  688.  * INPUTS:    struct Screen    *screen;    ptr to single-buffered screen
  689.  *        struct BitMap    **bmptr;    ptr to bitmap ptr for second buffer
  690.  *
  691.  * DESCRIPTION: Change a single-buffered Intuition screen into a
  692.  *        double-buffered screen.
  693.  *        If you already have your own bitmap for the secondary buffer,
  694.  *        bmptr should point to the bitmap pointer;
  695.  *        otherwise bmptr should point to a NULL pointer, in which case
  696.  *        a bitmap of the same depth/width/height as the screen is
  697.  *        dynamically created, and the pointer to this bitmap is
  698.  *        returned in *bmptr.
  699.  *
  700.  *        Note: you must not alter the bitmap pointer placed in *bmptr.
  701.  *
  702.  * RESULTS:    Returns non-zero on error.
  703.  *
  704.  * SEE ALSO:    unmakeDBufVQuick, swapDBufVQuick
  705.  */
  706.  
  707. /*
  708.  * NAME:    unmakeDBufVQuick
  709.  *
  710.  * SYNOPSIS:    err = unmakeDBufVQuick( screen, bmptr, bm );
  711.  *        short err;
  712.  *
  713.  * INPUTS:    struct Screen    *screen;    ptr to double-buffered screen
  714.  *        struct BitMap    **bmptr;    ptr to bitmap ptr for second buffer
  715.  *        struct BitMap    *bm;        ptr to bitmap to be freed
  716.  *
  717.  * DESCRIPTION: Changes a double-buffered screen [as made by makeDBufVQuick]
  718.  *        back into a single-buffered screen.
  719.  *        The screen's buffers are swapped if necessary to ensure that
  720.  *        a CloseScreen() will work properly.
  721.  *        If bm is non-NULL, the bitmap will be freed (de-allocated);
  722.  *        this is intended primarily to be used to free the bitmap that
  723.  *        was created by makeDBufVQuick if you did not previously have
  724.  *        a bitmap for the secondary buffer.
  725.  *
  726.  *        Note: the screen and bmptr parameters should be exactly the
  727.  *        same as those given to makeDBufVQuick.
  728.  *
  729.  * RESULTS:    Returns non-zero on error.
  730.  *
  731.  * SEE ALSO:    makeDBufVQuick, swapDBufVQuick
  732.  */
  733.  
  734. /*
  735.  * NAME:    swapDBufVQuick
  736.  *
  737.  * SYNOPSIS:    err = swapDBufVQuick( screen, minterm );
  738.  *        short err;
  739.  *
  740.  * INPUTS:    struct Screen    *screen;    ptr to double-buffered screen
  741.  *        SHORT        minterm;    minterm for the copy
  742.  *
  743.  * DESCRIPTION: Switch the display and draw buffers for the screen.
  744.  *        The minterm is used to specify the type of blit used to copy
  745.  *        the new displayed buffer (source) to the new hidden/drawing
  746.  *        buffer (dest).
  747.  *        Some common minterms are:
  748.  *            0x000    - clear destination
  749.  *            0x0c0    - vanilla copy (result: source only)
  750.  *            0x0a0    - no copy (result: dest only)
  751.  *
  752.  *        Note: this routine hums along fine if the screen is not
  753.  *        actually double-buffered, doing no swap and no copy.
  754.  *
  755.  * RESULTS:    Returns non-zero on error.
  756.  *
  757.  * SEE ALSO:    makeDBufVQuick, unmakeDBufVQuick
  758.  */
  759.  
  760. /*
  761.  * NAME:    makeDualPlayfield
  762.  *
  763.  * SYNOPSIS:    err = makeDualPlayfield( screen, ri, reldepth );
  764.  *        short err;
  765.  *
  766.  * INPUTS:    struct Screen    *screen;    ptr to single-playfield screen
  767.  *        struct RasInfo    *ri;        ptr to RasInfo for second playfield
  768.  *        SHORT    reldepth;        depth of second playfield relative
  769.  *                          to first playfield (0 or -1)
  770.  *
  771.  * DESCRIPTION: Change a single-playfield Intuition screen into a
  772.  *        dual-playfield screen.
  773.  *        Fully initializes the RasInfo struct pointed at by ri,
  774.  *        and links it into the screen's RasInfo.
  775.  *        A bitmap of the appropriate depth and same width/height will
  776.  *        be dynamically created - the pointer is returned in ri->BitMap
  777.  *        The possible depth combinations are limited (see RKM), but
  778.  *        essentially:
  779.  *        - the first playfield can be at most depth 3
  780.  *        - the second playfield must have same depth or 1 less.
  781.  *        Therefore "reldepth" must be 0 or -1.
  782.  *        NOTE: present default: the first playfield is given video
  783.  *        priority over the second playfield (though you can set the
  784.  *        PFBA flag yourself if you do it right - CAUTION!).
  785.  *
  786.  *        Note: you must have opened the screen using OpenScreen()
  787.  *        without specifying DUALPF in the NewScreen's Flags field before
  788.  *        calling this routine to keep things consistent (1.2 Intuition
  789.  *        does not support opening/closing DUALPF screens properly).
  790.  *
  791.  * RESULTS:    Returns non-zero on error.
  792.  *
  793.  * SEE ALSO:    unmakeDualPlayfield
  794.  */
  795.  
  796. /*
  797.  * NAME:    unmakeDualPlayfield
  798.  *
  799.  * SYNOPSIS:    err = unmakeDualPlayfield( screen );
  800.  *        short err;
  801.  *
  802.  * INPUTS:    struct Screen    *screen;    pointer to dual-playfield screen
  803.  *
  804.  * DESCRIPTION: Changes a dual-playfield screen [as made by makeDualPlayfield]
  805.  *        back into a single-playfield screen.
  806.  *
  807.  *        NOTE: The bitmap *currently* used for the second-playfield is
  808.  *        de-allocated, making the second playfield's RasInfo's BitMap
  809.  *        pointer invalid. This will be the same bitmap that was
  810.  *        allocated by makeDualPlayfield ONLY if you don't play
  811.  *        around with the second-playfield's RasInfo's BitMap pointer.
  812.  *
  813.  *        Note: you must call this routine before you do a CloseScreen()
  814.  *        to keep things consistent (1.2 Intuition does not fully support
  815.  *        opening/closing DUALPF screens properly).
  816.  *
  817.  * RESULTS:    Returns non-zero on error (eg screen is NULL or screen is not
  818.  *        dual-playfield).
  819.  *
  820.  * SEE ALSO:    makeDualPlayfield
  821.  */
  822.  
  823. /*
  824.  * NAME:    gimmeFont
  825.  *
  826.  * REQUISITES:    struct DiskfontBase *DiskfontBase;    properly initialized
  827.  *
  828.  * SYNOPSIS:    textfont = gimmeFont( textattr );
  829.  *        struct TextFont *textfont;
  830.  *
  831.  * INPUTS:    struct TextAttr *textattr;        ptr to font description
  832.  *
  833.  * DESCRIPTION: Load specified font from disk (check in memory first).
  834.  *        NOTE: the textattr may be altered to reflect actual font found.
  835.  *
  836.  *        NOTE: you must have a global variable named DiskfontBase,
  837.  *        declared as a "struct DiskfontBase *", already initialized by
  838.  *        by opening the diskfont.library with code similar to the
  839.  *        following:
  840.  *            struct DiskfontBase *DiskfontBase;
  841.  *            DiskfontBase = (struct DiskfontBase *)
  842.  *                    OpenLibrary("diskfont.library", 0L);
  843.  *            { check for NULL pointer returned on error }
  844.  *
  845.  * RESULTS:    Returns TextFont or NULL on error.
  846.  *        The TextAttr's ta_YSize and ta_Style fields are altered to
  847.  *        reflect those of the actual font found if successful.
  848.  *
  849.  * SEE ALSO:    gimmeFontLazy, getRidOfFont
  850.  */
  851.  
  852. /*
  853.  * NAME:    gimmeFontLazy
  854.  *
  855.  * REQUISITES:    struct DiskfontBase *DiskfontBase;    properly initialized
  856.  *
  857.  * SYNOPSIS:    textfont = gimmeFontLazy( name, size );
  858.  *        struct TextFont *textfont;
  859.  *
  860.  * INPUTS:    UBYTE    *name;        name of desired font
  861.  *        UWORD    size;        y-size of desired font
  862.  *
  863.  * DESCRIPTION: Load specified font from disk (check in memory first).
  864.  *        NOTE: a similar font may be used if the exact font is not found.
  865.  *
  866.  *        NOTE: you must have a global variable named DiskfontBase --
  867.  *        see gimmeFont for information on how to initialize it.
  868.  *
  869.  * RESULTS:    Returns TextFont or NULL on error.
  870.  *
  871.  * SEE ALSO:    gimmeFont, getRidOfFont
  872.  */
  873.  
  874. /*
  875.  * NAME:    getRidOfFont
  876.  *
  877.  * SYNOPSIS:    err = getRidOfFont( textfont );
  878.  *        short err;
  879.  *
  880.  * INPUTS:    struct TextFont *textfont;    pointer to TextFont
  881.  *
  882.  * DESCRIPTION: Releases access to a disk font obtained via gimmeFont(Quick).
  883.  *
  884.  * RESULTS:    Returns non-zero on error.
  885.  *
  886.  * SEE ALSO:    gimmeFont, gimmeFontLazy
  887.  */
  888.  
  889. /*
  890.  * NAME:    getRidOfGadgets
  891.  *
  892.  * SYNOPSIS:    err = getRidOfGadgets( firstgadget );
  893.  *        short err;
  894.  *
  895.  * INPUTS:    struct Gadget    *firstgadget;        pointer to first Gadget
  896.  *
  897.  * DESCRIPTION: Frees memory allocated for each gadget in chain, starting
  898.  *        with firstgadget, using chainFreeMem.
  899.  *
  900.  *        NOTE: uses a gadget's UserData field as pointer to head of
  901.  *        memory-chain, as returned by chainAllocMem and set by the
  902.  *        other gimme-gadget routines.
  903.  *
  904.  * RESULTS:    Returns non-zero on error.
  905.  *
  906.  * SEE ALSO:    chainAllocMem, chainFreeMem, gimmeXXXGadget
  907.  */
  908.  
  909. /*
  910.  * NAME:    gimmeBoolGadget
  911.  *
  912.  * REQUISITES:    struct GfxBase *GfxBase;    properly initialized - but only if
  913.  *                          ysize == -1, !window && !textattr
  914.  *
  915.  * SYNOPSIS:    gp = gimmeBoolGadget( window, id, left, top, xsize, ysize,
  916.  *                    s, s2, textattr, myflags );
  917.  *        struct Gadget *gp;
  918.  *
  919.  * INPUTS:    struct Window    *window;    window for gadget, or NULL
  920.  *        USHORT    id;            non-zero id for gadget
  921.  *        SHORT    left;            left offset in pixels
  922.  *        SHORT    top;            top offset in pixels
  923.  *        SHORT    xsize;            total width in pixels, or -1
  924.  *        SHORT    ysize;            total height in pixels, or -1
  925.  *        UBYTE    *s;            main text string
  926.  *        UBYTE    *s2;            auxiliary text string, or NULL
  927.  *        struct TextAttr *textattr;  pointer to font, or NULL
  928.  *        ULONG    myflags;        flags for the routine
  929.  *
  930.  * DESCRIPTION: Allocate and initialize a boolean Gadget structure,
  931.  *        including a border.
  932.  *        The border is created appropriately enough to enclose
  933.  *        the string nicely. Note: this routine succeeds even if no
  934.  *        border was allocated (check gp->GadgetRender for a non-NULL
  935.  *        value if you want to be sure that a border was allocated).
  936.  *
  937.  *        NOTE: For text (with a border), not an image.
  938.  *
  939.  *        If the window is non-NULL, some further customization of the
  940.  *        gadget is done; notably the FgPen, BgPen and DrawMode of the
  941.  *        window's rastport are used.
  942.  *        If xsize or ysize are non-positive (use -1), appropriate
  943.  *        value(s) are calculated to enclose the string nicely.
  944.  *        If the auxiliary string s2 is NULL, a *hit select* boolean
  945.  *        gadget is constructed, otherwise a *toggle select* boolean
  946.  *        gadget is constructed -- NOTE: due to the odd nature of the
  947.  *        toggle-selected text, you must use toggleBoolGadget upon
  948.  *        receiving the GADGETDOWN message to effect the toggle visibly
  949.  *        in the window.
  950.  *
  951.  *        If xsize is non-positive and s2 is non-NULL,
  952.  *        the border is constructed to enclose the longer string nicely
  953.  *        and the shorter string is centred in the box accordingly,
  954.  *        without residue of the longer string when displayed (toggled).
  955.  *        The textattr can be NULL to use the default font.
  956.  *        The flags (see gimmelib/postext.h) allow special effects for
  957.  *        positioning the gadget:
  958.  *            - if xsize is "real" (positive):
  959.  *            - x-flags cause the final gadget box to be placed
  960.  *              accordingly within the region from left to left+xsize
  961.  *              (eg. x-centre means the gadget is centred within
  962.  *                xsize bits, offset by the left parm)
  963.  *            - if xsize is -1 (non-postive):
  964.  *            - the left parameter is taken to be the coordinate
  965.  *              as specified by the x-flags
  966.  *              (eg. x-centre means the left parm is actually the
  967.  *                centre of the gadget in the x-direction)
  968.  *            - the y-flags always modify the meaning of the top parm
  969.  *              (eg. y-centre means the top parm is actually the
  970.  *                centre of the gadget in the y-direction)
  971.  *
  972.  *        NOTE: The auxiliary string's IntuiText is stored in
  973.  *        the gadget's SelectRender field. You must leave this field
  974.  *        alone, which also means do not use the GADGHIMAGE flag.
  975.  *        The two strings can be switched and displayed by using
  976.  *        toggleBoolGadget.
  977.  *
  978.  *        NOTE: To remove the border permanently, do something similar
  979.  *        to the following (with appropriate error checking):
  980.  *            gp = gimmeBoolGadget(...);
  981.  *            pluckChainMem( &gp->UserData, gp->GadgetRender );
  982.  *            gp->GadgetRender = NULL;
  983.  *        (the pluckChainMem is not absolutely necessary, since the
  984.  *        border's memory would be freed when getRidOfGadgets is called)
  985.  *
  986.  *        If all goes well, the head pointer to chained memory for the
  987.  *        gadget and its other required structures is stored in the
  988.  *        gp->UserData field. You must preserve this pointer!!
  989.  *        If you need to use the UserData yourself, be sure to save
  990.  *        gp->UserData somewhere safe after calling this routine.
  991.  *        When you are done with the gadget you must ensure that the
  992.  *        chained memory head pointer is restored into gp->UserData
  993.  *        before you call getRidOfGadgets.
  994.  *
  995.  *        NOTE: if you supply an auxiliary string s2 to create a toggle
  996.  *        gadget, and window is non-NULL, then the window's rastport's
  997.  *        drawmode should be JAM2 otherwise visual confusion may occur
  998.  *        upon toggling and/or clearing.
  999.  *
  1000.  * RESULTS:    Returns pointer to boolean gadget, or NULL.
  1001.  *        Note: The gadget is NOT added to the window.
  1002.  *
  1003.  * SEE ALSO:    toggleBoolGadget, getRidOfGadgets, gimmeBoolImageGadget
  1004.  */
  1005.  
  1006. /*
  1007.  * NAME:    gimmeBoolImageGadget
  1008.  *
  1009.  * SYNOPSIS:    gp = gimmeBoolImageGadget( window, id, left, top, depth, width,
  1010.  *                        height, myflags, dep2, wid2, ht2 );
  1011.  *        struct Gadget *gp;
  1012.  *
  1013.  * INPUTS:    struct Window    *window;    window for gadget, or NULL
  1014.  *        USHORT    id;            non-zero id for gadget
  1015.  *        SHORT    left;            left offset in pixels
  1016.  *        SHORT    top;            top offset in pixels
  1017.  *        SHORT    depth;            depth of primary image
  1018.  *        SHORT    width;            width of primary image, in pixels
  1019.  *        SHORT    height;         height of primary image, in pixels
  1020.  *        ULONG    myflags;        flags for the routine
  1021.  *        SHORT    dep2;            depth of secondary image, or <= 0
  1022.  *        SHORT    wid2;            width of secondary image, or <= 0
  1023.  *        SHORT    ht2;            height of secondary image, or <= 0
  1024.  *
  1025.  * DESCRIPTION: Allocate and initialize a boolean Gadget structure,
  1026.  *        including Image structure(s) and data memory (via gimmeImage)
  1027.  *        for the primary image, and for the secondary image if the
  1028.  *        3 size specifications for it are strictly positive.
  1029.  *        Note that for the primary image, you can specify zero for any
  1030.  *        of its dimensions so that an Image structure but no data memory
  1031.  *        is allocated.
  1032.  *
  1033.  *        NOTE: For images, not text.
  1034.  *
  1035.  *        If the secondary image's dimensions are improper, a *hit select*
  1036.  *        boolean gadget is constructed, otherwise a *toggle select*
  1037.  *        boolean gadget is constructed.
  1038.  *        NOTE: if you wish the secondary image to merely be highlighting
  1039.  *        imagery for a *hit select* boolean gadget, you should do this:
  1040.  *            gp->Activation = RELVERIFY;
  1041.  *        after this function call (note your two images should overlap
  1042.  *        exactly to keep things clean on the screen).
  1043.  *        NOTE: if you wish to toggle manually, do the following:
  1044.  *            gp->Flags = GADGIMAGE | GADGHNONE;
  1045.  *            gp->Activation = GADGIMMEDIATE;
  1046.  *        after this function call. Then, when you receive a GADGETDOWN
  1047.  *        message, call toggleBoolGadget to switch the imagery. This is
  1048.  *        similar to the system toggle select except that toggleBoolGadget
  1049.  *        erases the current image before drawing the "alternate" image
  1050.  *        and redefines the gadget's select box for the new image.
  1051.  *
  1052.  *        The flags (see gimmelib/postext.h) alter the meaning of the
  1053.  *        top and left parameters, with respect to the size of the
  1054.  *        primary image.
  1055.  *
  1056.  *        If all goes well, the head pointer to chained memory for the
  1057.  *        gadget and its other required structures is stored in the
  1058.  *        gp->UserData field. You must preserve this pointer!!
  1059.  *        If you need to use the UserData yourself, be sure to save
  1060.  *        gp->UserData somewhere safe after calling this routine.
  1061.  *        When you are done with the gadget you must ensure that the
  1062.  *        chained memory head pointer is restored into gp->UserData
  1063.  *        before you call getRidOfGadgets.
  1064.  *
  1065.  * RESULTS:    Returns pointer to boolean gadget, or NULL.
  1066.  *        Note: The gadget is NOT added to the window.
  1067.  *
  1068.  * SEE ALSO:    toggleBoolGadget, getRidOfGadgets, gimmeBoolGadget
  1069.  */
  1070.  
  1071. /*
  1072.  * NAME:    gimmePropGadget
  1073.  *
  1074.  * SYNOPSIS:    gp = gimmePropGadget( window, id, left, top, xsize, ysize,
  1075.  *                       label, textattr, activflags, propflags );
  1076.  *        struct Gadget *gp;
  1077.  *
  1078.  * INPUTS:    struct Window    *window;    window for gadget, or NULL
  1079.  *        USHORT    id;            non-zero id for gadget
  1080.  *        SHORT    left;            left offset in pixels
  1081.  *        SHORT    top;            top offset in pixels
  1082.  *        SHORT    xsize;            total width in pixels
  1083.  *        SHORT    ysize;            total height in pixels
  1084.  *        UBYTE    *label;         gadget label, or NULL
  1085.  *        struct TextAttr *textattr;  pointer to font, or NULL
  1086.  *        ULONG    activflags;        gadget Activation flags
  1087.  *        ULONG    propflags;        flags for PropInfo
  1088.  *
  1089.  * DESCRIPTION: Allocate and initialize a string Gadget structure,
  1090.  *        including PropInfo and optional label.
  1091.  *        If the window is non-NULL, some further customization of the
  1092.  *        gadget is done; notably the FgPen, BgPen and DrawMode of the
  1093.  *        window's rastport are used for the label.
  1094.  *        The xsize and ysize parms define the size of the actual,
  1095.  *        gadget, NOT including the (optional) label.
  1096.  *        Note: if xsize and/or ysize are non-positive, you must set
  1097.  *        the appropriate flags (such as GRELWIDTH, GRELHEIGHT) in the
  1098.  *        gadget's Flags field after this routine returns.
  1099.  *        If label is non-NULL, a label is set up with the actual prop
  1100.  *        gadget to the right of the label.
  1101.  *        The textattr can be NULL to use the default font.
  1102.  *        The activflags are set in the gadget's Activation field.
  1103.  *        The propflags are set in the gadget's PropInfo structure - see
  1104.  *        gimmePropInfo for details on how these flags are used.
  1105.  *        Note: if you wish to change the knob imagery to your own, do
  1106.  *        something similar to the following after this routine:
  1107.  *            gp->GadgetRender = (APTR) <your image or border>;
  1108.  *            ((struct PropInfo *)gp->SpecialInfo)->Flags &= ~AUTOKNOB;
  1109.  *            gp->Flags &= ~GADGIMAGE;    ;; ONLY if you want a BORDER
  1110.  *
  1111.  *        If all goes well, the head pointer to chained memory for the
  1112.  *        gadget and its other required structures is stored in the
  1113.  *        gp->UserData field. You must preserve this pointer!!
  1114.  *        If you need to use the UserData yourself, be sure to save
  1115.  *        gp->UserData somewhere safe after calling routine.
  1116.  *        When you are done with the gadget you must ensure that the
  1117.  *        chained memory head pointer is restored into gp->UserData
  1118.  *        before you call getRidOfGadgets.
  1119.  *
  1120.  * RESULTS:    Returns pointer to prop gadget, or NULL.
  1121.  *        Note: The gadget is NOT added to the window.
  1122.  *
  1123.  * SEE ALSO:    getRidOfGadgets, gimmePropInfo
  1124.  */
  1125.  
  1126. /*
  1127.  * NAME:    gimmePropInfo
  1128.  *
  1129.  * SYNOPSIS:    pi = gimmePropInfo( memheadptr, flags );
  1130.  *        struct PropInfo *pi;
  1131.  *
  1132.  * INPUTS:    void    **memheadptr;    pointer to chained-memory head
  1133.  *        ULONG    flags;        flags for PropInfo
  1134.  *
  1135.  * DESCRIPTION: Allocate and initialize a PropInfo structure.
  1136.  *
  1137.  *        The PropInfo's flags are set to "AUTOKNOB | flags"
  1138.  *        which you can change after this function returns.
  1139.  *
  1140.  *        The allocated memory is chained to the memory chain pointed
  1141.  *        at by memheadptr using chainAllocMem.
  1142.  *        Eventually chainFreeMem should be called on the memhead.
  1143.  *
  1144.  * RESULTS:    Returns pointer to PropInfo, or NULL.
  1145.  *
  1146.  * SEE ALSO:    chainAllocMem, chainFreeMem
  1147.  */
  1148.  
  1149. /*
  1150.  * NAME:    gimmeStringGadget
  1151.  *
  1152.  * REQUISITES:    struct GfxBase *GfxBase;    properly initialized - but only
  1153.  *                          needed if !window && !textattr
  1154.  *
  1155.  * SYNOPSIS:    gp = gimmeStringGadget( window, id, left, top, width, maxbuf,
  1156.  *                    s, label, textattr, activflags );
  1157.  *        struct Gadget *gp;
  1158.  *
  1159.  * INPUTS:    struct Window    *window;    window for gadget, or NULL
  1160.  *        USHORT    id;            non-zero id for gadget
  1161.  *        SHORT    left;            left offset in pixels
  1162.  *        SHORT    top;            top offset in pixels
  1163.  *        SHORT    width;            total width in pixels
  1164.  *        SHORT    maxbuf;         maximum buffer size including '\0'
  1165.  *        UBYTE    *s;            initial text string
  1166.  *        UBYTE    *label;         gadget label, or NULL
  1167.  *        struct TextAttr *textattr;  pointer to font, or NULL
  1168.  *        ULONG    activflags;        gadget Activation flags
  1169.  *
  1170.  * DESCRIPTION: Allocate and initialize a string Gadget structure,
  1171.  *        including border, StringInfo, buffers and optional label.
  1172.  *        If the window is non-NULL, some further customization of the
  1173.  *        gadget is done; notably the FgPen, BgPen and DrawMode of the
  1174.  *        window's rastport are used for the label and border.
  1175.  *        The border is width pixels wide and high enough to enclose
  1176.  *        the string nicely. Note: this routine succeeds even if no
  1177.  *        border was allocated (check gp->GadgetRender for a non-NULL
  1178.  *        value if you want to be sure that a border was allocated).
  1179.  *        If you want to remove the border, do something similar to this:
  1180.  *            pluckChainMem( &gp->UserData, gp->GadgetRender );
  1181.  *            gp->GadgetRender = NULL;
  1182.  *        If label is non-NULL, a label is set up with the actual string
  1183.  *        gadget to the right of the label.
  1184.  *        NOTE: the width includes space taken by the label (if any).
  1185.  *        The textattr can be NULL to use the default font.
  1186.  *        The activflags are set in the gadget's Activation field.
  1187.  *
  1188.  *        Note: the actual string is rendered in the screen's font.
  1189.  *        This is normally the font specified when the screen is opened.
  1190.  *        However, doing a SetFont() on the screen's rastport to alter the
  1191.  *        font (and even if you change the screen's Font field as well)
  1192.  *        will cause the string gadget to be handled a little awkwardly:
  1193.  *        the initial rendering will occur in the screen's original font,
  1194.  *        and once the gadget is selected, the "new" font will be used for
  1195.  *        rendering; however, the "old" font's character width is used to
  1196.  *        determine which character in the string gadget is clicked on,
  1197.  *        which may result in some visual confusion.
  1198.  *
  1199.  *        If all goes well, the head pointer to chained memory for the
  1200.  *        gadget and its other required structures is stored in the
  1201.  *        gp->UserData field. You must preserve this pointer!!
  1202.  *        If you need to use the UserData yourself, be sure to save
  1203.  *        gp->UserData somewhere safe after calling routine.
  1204.  *        When you are done with the gadget you must ensure that the
  1205.  *        chained memory head pointer is restored into gp->UserData
  1206.  *        before you call getRidOfGadgets.
  1207.  *
  1208.  * RESULTS:    Returns pointer to string gadget, or NULL.
  1209.  *        Note: The gadget is NOT added to the window.
  1210.  *
  1211.  * SEE ALSO:    getRidOfGadgets, gimmeStringInfo
  1212.  */
  1213.  
  1214. /*
  1215.  * NAME:    gimmeStringInfo
  1216.  *
  1217.  * SYNOPSIS:    si = gimmeStringInfo( memheadptr, bufsize, s, flags );
  1218.  *        struct StringInfo *si;
  1219.  *
  1220.  * INPUTS:    void **memheadptr;  pointer to chained memory head
  1221.  *        SHORT bufsize;        maximum size including nullchar
  1222.  *        UBYTE *s;        initial string
  1223.  *        ULONG flags;        flags for StringInfo: only LONGINT checked
  1224.  *
  1225.  * DESCRIPTION: Allocate and initialize a StringInfo structure,
  1226.  *        including space for the main and undo buffers.
  1227.  *        If the LONGINT flag is set in flags, the initial string s
  1228.  *        should consist of a valid long integer in ascii format.
  1229.  *
  1230.  *        The allocated memory is chained to the memory chain pointed
  1231.  *        at by memheadptr using chainAllocMem.
  1232.  *        Eventually chainFreeMem should be called on the memhead.
  1233.  *
  1234.  * RESULTS:    Returns pointer to StringInfo, or NULL.
  1235.  *
  1236.  * SEE ALSO:    chainAllocMem, chainFreeMem
  1237.  */
  1238.  
  1239. /*
  1240.  * NAME:    clearGadgets
  1241.  *
  1242.  * SYNOPSIS:    err = clearGadgets( firstgadget, window, req, numgad );
  1243.  *        short err;
  1244.  *
  1245.  * INPUTS:    struct Gadget        *firstgadget;   first gadget to clear
  1246.  *        struct Window        *window;        gadget's window
  1247.  *        struct Requester    *req;        gadget's requester, or NULL
  1248.  *        SHORT            numgad;        # of gadgets to clear, or -1
  1249.  *
  1250.  * DESCRIPTION: Clear the imagery of numgad gadgets in a window, starting with
  1251.  *        firstgadget.
  1252.  *        If numgad is negative, the whole list starting with firstgadget
  1253.  *        is cleared. If numgad is zero, no gadgets are cleared.
  1254.  *        NOTE: the gadget cannot be in a requester, so if the req
  1255.  *        parameter is non-NULL, the gadget(s) will not be cleared and
  1256.  *        an error returned.
  1257.  *        NOTE: The requester is ignored unless the first gadget has the
  1258.  *        REQGADGET gadget type flag set; you should ensure that this flag
  1259.  *        is consistently set or clear in each gadget in the list.
  1260.  *        It is assumed that all gadgets are in the requester if the first
  1261.  *        one is.
  1262.  *        NOTE: the gadget(s) will be cleared regardless of whether it
  1263.  *        actually exists in the window or requester.
  1264.  *
  1265.  *        If RefreshGadgets() is called after this routine, the gadget(s)
  1266.  *        will be displayed normally.
  1267.  *
  1268.  *        NOTE: active "invisible" gadgets may look odd; especially a
  1269.  *        previously activated string gadget and when you click somewhere
  1270.  *        else, the cursor in the string gadget is redrawn by Intuition.
  1271.  *        The cause of this may be the following: if a string gadget has
  1272.  *        the GADGHCOMP flag set, then the cursor is drawn when a
  1273.  *        RefreshGadgets() is done (possibly only if the gadget is in a
  1274.  *        requester).
  1275.  *
  1276.  * RESULTS:    Returns non-zero on error.
  1277.  *        Note that the Gadget's display on screen is cleared to the
  1278.  *        background colour of the window's rastport immediately.
  1279.  *
  1280.  * SEE ALSO:    RefreshGList, RemoveGList, AddGList
  1281.  */
  1282.  
  1283. /*
  1284.  * NAME:    toggleBoolGadget
  1285.  *
  1286.  * SYNOPSIS:    error = toggleBoolGadget( window, gadget, req );
  1287.  *        short error;
  1288.  *
  1289.  * INPUTS:    struct Window    *window;    gadget's window
  1290.  *        struct Gadget    *gadget;    boolean gadget to toggle
  1291.  *        struct Requester *req;        gadget's requester, or NULL
  1292.  *
  1293.  * DESCRIPTION: Toggle a boolean gadget's text OR image, by switching it
  1294.  *        with the alternative text or image respectively.
  1295.  *
  1296.  *        If it is a text gadget:
  1297.  *            NOTE: the alternative text pointer is originally stored in
  1298.  *            the gadget's SelectRender field by gimmeBoolGadget.
  1299.  *            You must leave this field alone, which also means do not use
  1300.  *            the GADGHIMAGE flag.
  1301.  *        If it is an image gadget:
  1302.  *            the current ("old") image is erased before the new image is
  1303.  *            drawn, and the select box of the gadget is altered to the
  1304.  *            dimensions of the new image (this works perfectly only if
  1305.  *            the image's top left corner is the same as the gadget's).
  1306.  *
  1307.  * RESULTS:    Returns non-zero on error.
  1308.  *        Note: this routine only refreshes this gadget.
  1309.  *
  1310.  * SEE ALSO:    gimmeBoolGadget, clearGadgets
  1311.  */
  1312.  
  1313. /*
  1314.  * NAME:    findGadget
  1315.  *
  1316.  * SYNOPSIS:    gp = findGadget( firstgadget, id );
  1317.  *        struct Gadget *gp;
  1318.  *
  1319.  * INPUTS:    struct Gadget    *firstgadget;        pointer to Gadget list
  1320.  *        USHORT        id;            id of Gadget being sought
  1321.  *
  1322.  * DESCRIPTION: Search linked list of Gadgets, starting with firstgadget,
  1323.  *        for the first Gadget with GadgetID equal to id.
  1324.  *
  1325.  * RESULTS:    Returns pointer to Gadget matching the id, or NULL if none.
  1326.  */
  1327.  
  1328. /*
  1329.  * NAME:    findMyFirstGadget
  1330.  *
  1331.  * SYNOPSIS:    gp = findMyFirstGadget( window, id );
  1332.  *        struct Gadget *gp;
  1333.  *
  1334.  * INPUTS:    struct Gadget    *firstgadget;        pointer to Gadget list
  1335.  *        USHORT        id;            threshold id to skip over
  1336.  *
  1337.  * DESCRIPTION: Search linked list of Gadgets, starting with firstgadget,
  1338.  *        for the first Gadget with GadgetID strictly greater than id.
  1339.  *
  1340.  * RESULTS:    Returns pointer to first Gadget with a greater id,
  1341.  *        or NULL if none.
  1342.  */
  1343.  
  1344. /*
  1345.  * NAME:    gimmeGraph
  1346.  *
  1347.  * SYNOPSIS:    gr = gimmeGraph( newgraph, bitmap, areainfo, tmpras );
  1348.  *        GRAPH *gr;
  1349.  *
  1350.  * INPUTS:    struct NEWGRAPH *newgraph;    ptr to initialized NEWGRAPH
  1351.  *        struct BitMap    *bitmap;    bitmap pointer, or NULL
  1352.  *        struct AreaInfo *areainfo;    areainfo pointer, or NULL
  1353.  *        struct TmpRas    *tmpras;    tmpras pointer, or NULL
  1354.  *
  1355.  * DESCRIPTION: Create and initialize a GRAPH structure,
  1356.  *        according to the specifications in the newgraph.
  1357.  *        The axes and title will be rendered immediately unless the
  1358.  *        appropriate flag is set, in which case you can modify the GRAPH
  1359.  *        structure, then call drawGraphAxes yourself after this routine.
  1360.  *
  1361.  *        NOTE: currently the graph routines only properly support 1st
  1362.  *        quadrant graphing with a right-handed coordinate system
  1363.  *        (ie the axes should increase in value up and to the right).
  1364.  *        If you use scrolling (via DELTA flags), you should avoid
  1365.  *        values that fall exactly on an axis.
  1366.  *
  1367.  *        If the newgraph's rastport pointer is non-NULL, the actual
  1368.  *        rastport is copied into the graph structure, leaving the
  1369.  *        rastport pointed at by the newgraph forever untouched;
  1370.  *        otherwise the graph's rastport is initialized by InitRastPort().
  1371.  *        If bitmap is non-NULL, the bitmap pointer is copied into the
  1372.  *        graph's rastport's bitmap pointer.
  1373.  *        NOTE: if you specified a rastport in the newgraph and no bitmap
  1374.  *        parameter, the bitmap in that rastport will be used; otherwise
  1375.  *        you MUST specify a valid bitmap pointer as a parameter.
  1376.  *
  1377.  *        The areainfo and tmpras parameters go together, and are used
  1378.  *        only if either or both FILLTO flags are set.
  1379.  *        If areainfo (or tmpras) is non-NULL, the pointer will be set
  1380.  *        in the graph's rastport. If areainfo (or tmpras) is NULL, then
  1381.  *        an AreaInfo struct and vector buffer (or TmpRas struct and a
  1382.  *        raster the same size as the bitmap) are allocated for you.
  1383.  *        NOTE: if you specify the same areainfo and/or tmpras for two
  1384.  *        or more graphs, you must ensure that any addToGraph using FILLTO
  1385.  *        is not done concurrently, since technically the areainfo/tmpras
  1386.  *        structs should be unique for each graph.
  1387.  *
  1388.  *        The graphing routines are intended to be reasonably flexible;
  1389.  *        you can alter the fonts and colours for the various titles and
  1390.  *        labvels (title refers to words; label refers to the numbers on
  1391.  *        an axis) after this routine -- currently, the labels default to
  1392.  *        use the same font as their respective titles; the axes' title
  1393.  *        colours default to the same as the title colour; and the axes'
  1394.  *        label colours default to the axes colour.
  1395.  *        NOTE: if you wish to use different fonts for the labels, you
  1396.  *        can set the appropriate graph's textfont pointer, for example
  1397.  *        by assigning the title-textfont to the x-label-textfont, or
  1398.  *        setting it to NULL to use the "default" font;
  1399.  *        however, it is recommended that you do not introduce new fonts
  1400.  *        unless you know how to handle fonts properly (in particular
  1401.  *        do not play around with the three title font pointers).
  1402.  *
  1403.  *        Points are added to the graph dynamically using addToGraph.
  1404.  *
  1405.  *        See gimmelib/graph.h for descriptions of the various graphing
  1406.  *        structures and flags; note that some of the newgraph flags
  1407.  *        apply to how axis information is used.
  1408.  *
  1409.  *        Note: all allocated memory, including the GRAPH struct itself,
  1410.  *        is chained and the header is stored in the GRAPH's memhead
  1411.  *        field, which is used by getRidOfGraph to deallocate memory.
  1412.  *        You should use getRidOfGraph to free all the memory allocated
  1413.  *        by this routine.
  1414.  *
  1415.  * RESULTS:    Returns a pointer to a GRAPH, or NULL if anything went wrong.
  1416.  *
  1417.  * SEE ALSO:    addToGraph, getRidOfGraph, gimmeFont, drawGraphAxes,
  1418.  *        chainAllocMem
  1419.  */
  1420.  
  1421. /*
  1422.  * NAME:    getRidOfGraph
  1423.  *
  1424.  * SYNOPSIS:    err = getRidOfGraph( graph );
  1425.  *        short err;
  1426.  *
  1427.  * INPUTS:    GRAPH    *graph;     pointer to a GRAPH structure
  1428.  *
  1429.  * DESCRIPTION: Close a graph, freeing any allocated memory and releasing
  1430.  *        access to fonts accessed by gimmeGraph.
  1431.  *        May clear the graph first if the flags dictate it.
  1432.  *
  1433.  * RESULTS:    Returns non-zero on error.
  1434.  *
  1435.  * SEE ALSO:    gimmeGraph, clearGraph, getRidOfFont, chainFreeMem
  1436.  */
  1437.  
  1438. /*
  1439.  * NAME:    clearGraph
  1440.  *
  1441.  * SYNOPSIS:    clearGraph( graph );
  1442.  *
  1443.  * INPUTS:    GRAPH    *graph;     pointer to a GRAPH structure
  1444.  *
  1445.  * DESCRIPTION: Clear a graph.
  1446.  *        Effectively this means drawing the axes, labels and titles
  1447.  *        in the background colour and then clearing the rectangular
  1448.  *        region of the graph (bounded by the axes).
  1449.  *        Note: the graph struct is otherwise unchanged after this call.
  1450.  *
  1451.  * SEE ALSO:    gimmeGraph, getRidOfGraph
  1452.  */
  1453.  
  1454. /*
  1455.  * NAME:    resetGraph
  1456.  *
  1457.  * SYNOPSIS:    resetGraph( graph );
  1458.  *
  1459.  * INPUTS:    GRAPH    *graph;     pointer to a GRAPH structure
  1460.  *
  1461.  * DESCRIPTION: Resets a graph to the beginning.
  1462.  *        Effectively this means clearing the graph, re-initializing
  1463.  *        appropriate variables such as first and last point, undoing
  1464.  *        the effects of any scrolling, etc. and redrawing the "empty"
  1465.  *        graph if the graph's flags dictate it.
  1466.  *
  1467.  * SEE ALSO:    gimmeGraph, clearGraph, drawGraphAxes, getRidOfGraph
  1468.  */
  1469.  
  1470. /*
  1471.  * NAME:    drawGraphAxesOnly
  1472.  *
  1473.  * SYNOPSIS:    drawGraphAxesOnly( graph );
  1474.  *
  1475.  * INPUTS:    GRAPH    *graph;     pointer to a GRAPH structure
  1476.  *
  1477.  * DESCRIPTION: Draw the axes (lines only -- not labels) of a graph.
  1478.  *        Existing axes (if any) are NOT cleared first.
  1479.  *
  1480.  * SEE ALSO:    drawGraphAxes, gimmeGraph, clearGraph
  1481.  */
  1482.  
  1483. /*
  1484.  * NAME:    drawGraphAxes
  1485.  *
  1486.  * SYNOPSIS:    drawGraphAxes( graph );
  1487.  *
  1488.  * INPUTS:    GRAPH    *graph;     pointer to a GRAPH structure
  1489.  *
  1490.  * DESCRIPTION: Draw the axes including labels, titles and graph title
  1491.  *        of a graph in appropriate fonts, colours and positions.
  1492.  *        This means main title centred over the graph quad, the x-title
  1493.  *        centred under the x-axis (and labels), and the y-axis vertical
  1494.  *        and centred left of the y-axis (and labels).
  1495.  *
  1496.  *        Existing axes, labels and titles (if any) are NOT cleared first.
  1497.  *
  1498.  * RESULTS:    Returns the maximum width required for the labels (not titles).
  1499.  *
  1500.  * SEE ALSO:    drawGraphAxes, gimmeGraph, clearGraph, drawGraphTitle,
  1501.  *            drawGraphXtitle, drawGraphYtitle
  1502.  */
  1503.  
  1504. /*
  1505.  * NAME:    drawGraphTitle
  1506.  *
  1507.  * SYNOPSIS:    drawGraphTitle( graph, xoff, yoff, myflags );
  1508.  *
  1509.  * INPUTS:    GRAPH    *graph;     pointer to a GRAPH structure
  1510.  *        SHORT    xoff;        offset from y-axis in pixels
  1511.  *        SHORT    yoff;        offset from x-axis in pixels
  1512.  *        ULONG    myflags;    flags ala positionText
  1513.  *
  1514.  * DESCRIPTION: Draw the main title for a graph in the appropriate font
  1515.  *        and colour at (xoff, yoff) relative to the graph origin
  1516.  *        as modified by myflags via positionText.
  1517.  *        NOTE: yoff is positive upwards from the x-axis, and negative
  1518.  *        downwards (opposite to the normal rastport offsets).
  1519.  *
  1520.  *        Existing title (if any) is NOT cleared first.
  1521.  *
  1522.  * SEE ALSO:    drawGraphAxes, gimmeGraph, clearGraph, positionText
  1523.  */
  1524.  
  1525. /*
  1526.  * NAME:    drawGraphXtitle
  1527.  *
  1528.  * SYNOPSIS:    drawGraphXtitle( graph, xoff, yoff, myflags );
  1529.  *
  1530.  * INPUTS:    GRAPH    *graph;     pointer to a GRAPH structure
  1531.  *        SHORT    xoff;        offset from y-axis in pixels
  1532.  *        SHORT    yoff;        offset from x-axis in pixels
  1533.  *        ULONG    myflags;    flags ala positionText
  1534.  *
  1535.  * DESCRIPTION: Draw the title for a graph's x-axis in the appropriate font
  1536.  *        and colour at (xoff, yoff) relative to the graph origin
  1537.  *        as modified by myflags via positionText.
  1538.  *        NOTE: yoff is positive upwards from the x-axis, and negative
  1539.  *        downwards (opposite to the normal rastport offsets).
  1540.  *
  1541.  *        Existing title (if any) is NOT cleared first.
  1542.  *
  1543.  * SEE ALSO:    drawGraphAxes, gimmeGraph, clearGraph, positionText
  1544.  */
  1545.  
  1546. /*
  1547.  * NAME:    drawGraphYtitle
  1548.  *
  1549.  * SYNOPSIS:    drawGraphYtitle( graph, xoff, yoff, myflags );
  1550.  *
  1551.  * INPUTS:    GRAPH    *graph;     pointer to a GRAPH structure
  1552.  *        SHORT    xoff;        offset from y-axis in pixels
  1553.  *        SHORT    yoff;        offset from x-axis in pixels
  1554.  *        ULONG    myflags;    flags ala positionText
  1555.  *
  1556.  * DESCRIPTION: Draw the title for a graph's y-axis in the appropriate font
  1557.  *        and colour at (xoff, yoff) relative to the graph origin
  1558.  *        as modified by myflags via positionText.
  1559.  *        NOTE: yoff is positive upwards from the x-axis, and negative
  1560.  *        downwards (opposite to the normal rastport offsets).
  1561.  *
  1562.  *        Existing y-title (if any) is NOT cleared first.
  1563.  *
  1564.  * SEE ALSO:    drawGraphAxes, gimmeGraph, clearGraph, positionText
  1565.  */
  1566.  
  1567. /*
  1568.  * NAME:    graphWriteLabel
  1569.  *
  1570.  * SYNOPSIS:    graphWriteLabel( graph, myflags, first, last, step )
  1571.  *
  1572.  * INPUTS:    GRAPH    *graph;     pointer to a GRAPH structure
  1573.  *        ULONG    myflags;    flags for this routine
  1574.  *        SHORT    first;        low coordinate to start at
  1575.  *        SHORT    last;        high coordinate to end at
  1576.  *        SHORT    step;        fixed step size, 0 for automagic size
  1577.  *
  1578.  * DESCRIPTION: Draw the labels for one axis of a graph in the appropriate font
  1579.  *        and colour (note: does not draw axis title).
  1580.  *
  1581.  *        Automagically labels an axis between the coords first and last
  1582.  *        inclusive (the first and last parms should be reasonable -- not
  1583.  *        checked).
  1584.  *        If step is zero (0) then labels for first and last are rendered,
  1585.  *        and as many labels as reasonably possible are placed starting
  1586.  *        next to first and going towards just before last, leaving a
  1587.  *        reasonable amount of space between labels.
  1588.  *        If step is strictly positive, then a label is written for the
  1589.  *        coords: first, first+step, first+step+step,...,last
  1590.  *        (note that if last is not n-steps away from first then a label
  1591.  *        for last itself will not be drawn).
  1592.  *        Note: the step size should not be too small (not checked).
  1593.  *
  1594.  *        NOTE: exact label "wording" depend on the axis scale and certain
  1595.  *        graph flags.
  1596.  *
  1597.  *        Warning: this is a very recursive routine (unless you give
  1598.  *        a fixed step size).
  1599.  *
  1600.  * RESULTS:    Returns the maximum width of the labels for this axis.
  1601.  *
  1602.  * SEE ALSO:    drawGraphAxes, gimmeGraph, clearGraph
  1603.  */
  1604.  
  1605. /*
  1606.  * NAME:    addToGraph
  1607.  *
  1608.  * SYNOPSIS:    addToGraph( graph, x, y );
  1609.  *
  1610.  * INPUTS:    GRAPH    *graph;     pointer to a GRAPH structure
  1611.  *        SHORT    x;        x coordinate of new point to add
  1612.  *        SHORT    y;        y coordinate of new point to add
  1613.  *
  1614.  * DESCRIPTION: Add a point to the graph, rendered according to the flags
  1615.  *        in the graph structure.
  1616.  *        This includes lines, block fills etc. as well as scrolling
  1617.  *        if necessary.
  1618.  *        Note: the point is moved to the boundary of the rectangular
  1619.  *        region defined by the origin and the size of the axes
  1620.  *        if the point would fall outside of this boundary.
  1621.  *
  1622.  *        NOTE: if either FILLTO flag is set in the graph, the proper
  1623.  *        initialized AreaInfo and TmpRas structures must exist
  1624.  *        (gimmeGraph takes care of this if either FILLTO flag was set
  1625.  *        when it was called) otherwise crashes will occur.
  1626.  *
  1627.  * SEE ALSO:    gimmeGraph, getRidOfGraph, drawGraphAxes
  1628.  */
  1629.  
  1630. /*
  1631.  * NAME:    addInputHandler
  1632.  *
  1633.  * SYNOPSIS:    ioreq = addInputHandler( handler, data, pri, name );
  1634.  *        struct IOStdReq *ioreq;
  1635.  *
  1636.  * INPUTS:    void    (*handler)();       address of handler routine
  1637.  *        APTR    data;            pointer to data area for handler
  1638.  *        BYTE    pri;            priority for the handler
  1639.  *        UBYTE    *name;            name for input handler, or NULL
  1640.  *
  1641.  * DESCRIPTION: Add an input handler to the system.
  1642.  *        The priority indicates the priority level of the input handler;
  1643.  *        note that Intuition operates at priority fifty (50).
  1644.  *        The name is optional.
  1645.  *
  1646.  *        Your "real" input handler routine should be written as if called
  1647.  *        from the following C-language statement (see manuals):
  1648.  *            newEventChain = handler( oldEventChain, data );
  1649.  *        This isn't entirely true... the routine "handler" should
  1650.  *        actually expect the oldEventChain and data parameters
  1651.  *        in A0 and A1 respectively (see manuals).
  1652.  *        IF your real input handler is written in C, make your real
  1653.  *        input handler act like the above C-language call and also
  1654.  *        you must set up an interface routine similar to the following:
  1655.  *          #asm
  1656.  *          _handler:
  1657.  *            MOVEM.L    D2/D3/A4/A6,-(sp)       ; save some registers
  1658.  *            MOVEM.L    A0/A1,-(sp)             ; set up parms for C
  1659.  *            JSR     _myrealhandler
  1660.  *            LEA     8(sp),sp                ; pop parms
  1661.  *            MOVEM.L    (sp)+,D2/D3/A4/A6       ; restore registers
  1662.  *            RTS                 ; return in D0
  1663.  *          #endasm
  1664.  *        then call this routine using "handler", NOT "myrealhandler",
  1665.  *        as the handler parameter.
  1666.  *
  1667.  *        NOTE: your "real" input handler may have to do a geta4() as
  1668.  *        the first thing (or the Lattice equivalent) to set up a special
  1669.  *        pointer for small code/data models.
  1670.  *
  1671.  *        NOTE: do not fiddle with the iorequest; in particular, you
  1672.  *        must not alter the ioreq->io_Data pointer.
  1673.  *
  1674.  * RESULTS:    Returns a pointer to a IOStdReq, or NULL if unsuccessful.
  1675.  *
  1676.  * SEE ALSO:    removeInputHandler
  1677.  */
  1678.  
  1679. /*
  1680.  * NAME:    removeInputHandler
  1681.  *
  1682.  * SYNOPSIS:    err = removeInputHandler( ioreq );
  1683. SHAR_EOF
  1684. #    End of shell archive
  1685. exit 0
  1686. -- 
  1687. Bob Page, U of Lowell CS Dept.  page@swan.ulowell.edu  ulowell!page
  1688. Have five nice days.
  1689.